<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Timers</title>
<meta name="author" content="Cory Sharp, Martin Turon, David Gay" />
<style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:date: $Date: 2009/02/03 23:07:32 $
:version: $Revision: 1.13 $
:copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.
*/
body {
  font-family: Times;
  font-size: 16px;
}

.first {
  margin-top: 0 ! important }

.last {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dd {
  margin-bottom: 0.5em }

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.attention, div.caution, div.danger, div.error, div.hint,
div.important, div.note, div.tip, div.warning, div.admonition {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

div.hint p.admonition-title, div.important p.admonition-title,
div.note p.admonition-title, div.tip p.admonition-title,
div.admonition p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em }

div.footer, div.header {
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 0em 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1 {
  font-family: Arial, sans-serif;
  font-size: 20px;
}

h1.title {
 text-align: center;
 font-size: 32px;
}

h2 {
 font-size: 16px;
 font-family: Arial, sans-serif;
}

h2.subtitle {
  text-align: center }

h3 {
 font-size: 12px;
 font-family: Arial, sans-serif;
}

hr {
  width: 75% }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.line-block {
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee;
  border-color: #000000;
  border-width: thin; 
  font-size: 14px
}

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.option-argument {
  font-style: italic }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

table {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.citation {
  border-left: solid thin gray ;
  padding-left: 0.5ex }

table.docinfo {
  margin: 2em 4em;
}

table.footnote {
  border-left: solid thin black ;
  padding-left: 0.5ex }

td, th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

th.docinfo-name, th.field-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap;
  }

h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
  font-size: 100% }

tt {}

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="timers">
<h1 class="title">Timers</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">102</td>
</tr>
<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Core Working Group</td>
</tr>
<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
</tr>
<tr><th class="docinfo-name">Status:</th>
<td>Final</td></tr>
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
<td>Cory Sharp, Martin Turon, David Gay</td></tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
requests discussion and suggestions for improvements.  Distribution
of this memo is unlimited.  This memo is in full compliance with
TEP 1.</p>
</div>
<div class="section">
<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This TEP proposes a Timer design that supports common timing
requirements both in precision and width across common hardware
configurations.  This TEP focuses on aligning the Timer abstraction
with the three-layer Hardware Abstraction Architecture (HAA).</p>
</div>
<div class="section">
<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Most microcontrollers offer a rich timer system, with features like:</p>
<ul class="simple">
<li>several counters, possibly of different widths, with multiple clocking options</li>
<li>one or more compare registers for each counter, which can trigger
interrupts, changes to output pins and changes to the counter value</li>
<li>capture of the time of input pin changes</li>
</ul>
<p>The interested reader can refer to Appendix A for a brief overview of
the timer hardware on some current TinyOS platforms.</p>
<p>TinyOS does not attempt to capture all this diversity in a
platform-independent fashion. Instead, following the principles of the
HAA[_tep2], each microcontroller should expose all this functionality
via components and interfaces at the HPL and, where appropriate, HAL levels.
However, two aspects of timers are sufficiently common and important
that they should be made available in a well-defined way: measuring time,
and triggering (possibly repeating) events at specific times. The rest
of this TEP specifies:</p>
<ul class="simple">
<li>a set of platform-independent interfaces for counting time and triggering
events (<a class="reference" href="#interfaces">2. Interfaces</a>)</li>
<li>guidelines on how each microcontroller's HAL SHOULD expose its timer hardware
in terms of the above interfaces (<a class="reference" href="#hal-guidelines">3. HAL guidelines</a>)</li>
<li>what components a microcontroller's timer HIL MUST implement
(<a class="reference" href="#hil-requirements">4. HIL requirements</a>)</li>
<li>a set of utility components whose use simplifies building the components
specified by the HAL guidelines and HIL requirements (<a class="reference" href="#utility-components">5. Utility components</a>)</li>
</ul>
<p>This TEP ends with appendices documenting, as an example, the mica2
timer subsystem implementation.</p>
</div>
<div class="section">
<h1><a id="interfaces" name="interfaces">2. Interfaces</a></h1>
<p>Before presenting the interfaces (2.2), we start with a general
discussion of the issues of precision, width and accuracy in
timer interfaces (2.1).</p>
<div class="section">
<h2><a id="precision-width-and-accuracy" name="precision-width-and-accuracy">2.1 Precision, Width and Accuracy</a></h2>
<p>Three fundamental properties of timers are <em>precision</em>, <em>width</em> and
<em>accuracy</em>.</p>
<p>Examples of precision are millisecond, a cycle of a 32kHz clock, and
microseconds.  All precisions presented in this TEP are in &quot;binary&quot;
units with respect to one second.  That is, one second contains 1024
binary milliseconds, 32768 32kHz ticks, or 1048576 microseconds.
This TEP emphasizes millisecond and 32kHz tick precisions while
reasonably accommodating other precisions. The use of &quot;binary&quot; units
is motivated by the common availability of hardware clocks driven
by a 32768Hz crystal.</p>
<p>Examples of widths are 8-bit, 16-bit, 32-bit, and 64-bit.  The width
for timer interfaces and components SHOULD be 32-bits.  This TEP
emphasizes 32-bit widths while reasonably accommodating other widths -
a particular platform may have good reasons not to expose a 32-bit
interface.</p>
<p>Accuracy reflects how closely a component conforms to the precision it
claims to provide. Accuracy is affected by issues such as clock drift (much
higher for internal vs crystal oscillators) and hardware limitations. As an
example of hardware limitations, a mica2 clocked at 7.37MHz cannot offer an
exact binary microsecond timer -- the closest it can come is 7.37MHz/8. Rather
than introduce a plethora of precisions, we believe it is often best to
pick the existing precision closest to what can be provided, along with
appropriate documentation. However, the accuracy MUST remain reasonable:
for instance, it would be inappropriate to claim that a millisecond timer
is a 32kHz timer.</p>
<p>This TEP parameterizes all interfaces by precision and some
interfaces by width.  This intentionally makes similar timer
interfaces with different precision or width mutually incompatible.
It also allows user code to clearly express and understand the
precision and width for a given timer interface. Accuracy is not
reflected in the interface type.</p>
<p>Precision is expressed as a dummy type -- TMilli, T32khz, and
TMicro -- written in the standard Timer.h header like this:</p>
<pre class="literal-block">
typedef struct { int notUsed; } TMilli; // 1024 ticks per second
typedef struct { int notUsed; } T32khz; // 32768 ticks per second
typedef struct { int notUsed; } TMicro; // 1048576 ticks per second
</pre>
<p>Note that the precision names are expressed as either frequency or
period, whichever is convenient.</p>
</div>
<div class="section">
<h2><a id="timer-interfaces" name="timer-interfaces">2.2 Timer interfaces</a></h2>
<p>This TEP proposes these timer interfaces:</p>
<pre class="literal-block">
interface Counter&lt; precision_tag, size_type &gt;
interface Alarm&lt; precision_tag, size_type &gt;
interface BusyWait&lt; precision_tag, size_type &gt;
interface LocalTime&lt; precision_tag &gt;
interface Timer&lt; precision_tag &gt;
</pre>
<p>The LocalTime and Timer interfaces are used primarily by user
applications and use a fixed width of 32-bits.  The Alarm, BusyWait,
and Counter interfaces are used by the TinyOS timer system and
advanced user components.</p>
</div>
<div class="section">
<h2><a id="counter" name="counter">Counter</a></h2>
<p>The Counter interface returns the current time and provides commands
and an event for managing overflow conditions.  These overflow
commands and events are necessary for properly deriving larger width
Counters from smaller widths.</p>
<pre class="literal-block">
interface Counter&lt;precision_tag,size_type&gt;
{
  async command size_type get();
  async command bool isOverflowPending();
  async command void clearOverflow();
  async event void overflow();
}
</pre>
<dl class="docutils">
<dt>get()</dt>
<dd>return the current time.</dd>
<dt>isOverflowPending()</dt>
<dd>return TRUE if the overflow flag is set for this counter, i.e., if and
only if an overflow event will occur after the outermost atomic
block exits.  Return FALSE otherwise.  This command only returns the
state of the overflow flag and causes no side effect.</dd>
<dt>clearOverflow()</dt>
<dd>cancel the pending overflow event clearing the overflow flag.</dd>
<dt>overflow()</dt>
<dd>signals that an overflow in the current time.  That is, the current
time has wrapped around from its maximum value to zero.</dd>
</dl>
</div>
<div class="section">
<h2><a id="alarm" name="alarm">Alarm</a></h2>
<p>Alarm components are extensions of Counters that signal an event
when their compare register detects the alarm time has been hit.
All commands and events of the Alarm interface are asynchronous (or
in &quot;interrupt context&quot;).  The Alarm interface provides a set of
&quot;basic&quot; commands for common usage and provides a set of &quot;extended&quot;
commands for advanced use.</p>
<pre class="literal-block">
interface Alarm&lt;precision_tag,size_type&gt;
{
  // basic interface
  async command void start( size_type dt );
  async command void stop();
  async event void fired();

  // extended interface
  async command bool isRunning();
  async command void startAt( size_type t0, size_type dt );
  async command size_type getNow();
  async command size_type getAlarm();
}
</pre>
<dl class="docutils">
<dt>start(dt)</dt>
<dd>cancel any previously running alarm and set to fire in dt time units
from the time of invocation.  The alarm will only fire once then
stop.</dd>
<dt>stop()</dt>
<dd>cancel any previously running alarm.</dd>
<dt>fired()</dt>
<dd>signals that the alarm has expired.</dd>
<dt>isRunning()</dt>
<dd>return TRUE if the alarm has been started and has not been cancelled
or has not yet fired.  FALSE is returned otherwise.</dd>
</dl>
<p>startAt(t0,dt)</p>
<blockquote>
<p>cancel any previously running alarm and set to fire at time t1 =
t0+dt.  This form allows a delay to be anchored to some time t0 taken
before the invocation of startAt.  The timer subsystem uses this form
internally, to be able to use of the full width of an alarm while also
detecting when a short alarm elapses prematurely.</p>
<p>The time <tt class="docutils literal"><span class="pre">t0</span></tt> is always assumed to be in the past. A value of <tt class="docutils literal"><span class="pre">t0</span></tt>
numerically greater than the current time (returned by <tt class="docutils literal"><span class="pre">getNow()</span></tt>)
represents a time from before the last wraparound.</p>
</blockquote>
<dl class="docutils">
<dt>getNow()</dt>
<dd>return the current time in the precision and width of the alarm.</dd>
<dt>getAlarm()</dt>
<dd>return the time the currently running alarm will fire or the time
that the previously running alarm was set to fire.  getAlarm can
be used with startAt to set an alarm from the previous alarm time,
as in startAt(getAlarm(),dt).  This pattern is used within the
fired() event to construct periodic alarms.</dd>
</dl>
</div>
<div class="section">
<h2><a id="busywait" name="busywait">BusyWait</a></h2>
<p>The BusyWait interface allows for very short synchronous delays.
BusyWait should be used sparingly and when an Alarm would not be
reasonably efficient or accurate.  The BusyWait interface replaces
the TOSH_uwait macro from TinyOS 1.x.</p>
<p>BusyWait blocks for no less than the specified amount of time.  No
explicit upper bound is imposed on the enacted delay, though it is
expected that the underlying implementation spins in a busy loop until
the specified amount of time has elapsed.</p>
<pre class="literal-block">
interface BusyWait&lt;precision_tag,size_type&gt;
{
  async command void wait( size_type dt );
}
</pre>
<dl class="docutils">
<dt>wait(dt)</dt>
<dd>block until at least dt time units have elapsed</dd>
</dl>
</div>
<div class="section">
<h2><a id="localtime" name="localtime">LocalTime</a></h2>
<p>The LocalTime interface exposes a 32-bit counter without overflow
utilities.  This is primarily for application code that does not
care about overflow conditions.</p>
<pre class="literal-block">
interface LocalTime&lt;precision_tag&gt;
{
  async command uint32_t get();
}
</pre>
<dl class="docutils">
<dt>get()</dt>
<dd>return the current time.</dd>
</dl>
</div>
<div class="section">
<h2><a id="timer" name="timer">Timer</a></h2>
<p>All commands and events of the Timer interface are synchronous (or
in &quot;task context&quot;).  The Timer interface provides a set of &quot;basic&quot;
commands for common usage and provides a set of &quot;extended&quot; commands
for advanced use.  The Timer interface allows for periodic events.</p>
<pre class="literal-block">
interface Timer&lt;precision_tag&gt;
{
  // basic interface
  command void startPeriodic( uint32_t dt );
  command void startOneShot( uint32_t dt );
  command void stop();
  event void fired();

  // extended interface
  command bool isRunning();
  command bool isOneShot();
  command void startPeriodicAt( uint32_t t0, uint32_t dt );
  command void startOneShotAt( uint32_t t0, uint32_t dt );
  command uint32_t getNow();
  command uint32_t gett0();
  command uint32_t getdt();
}
</pre>
<dl class="docutils">
<dt>startPeriodic(dt)</dt>
<dd>cancel any previously running timer and set to fire in dt time units
from the time of invocation.  The timer will fire periodically every
dt time units until stopped.</dd>
<dt>startOneShot(dt)</dt>
<dd>cancel any previously running timer and set to fire in dt time units
from the time of invocation.  The timer will only fire once then
stop.</dd>
<dt>stop()</dt>
<dd>cancel any previously running timer.</dd>
<dt>fired()</dt>
<dd>signals that the timer has expired (one-shot) or repeated (periodic).</dd>
<dt>isRunning()</dt>
<dd>return TRUE if the timer has been started and has not been cancelled
and has not fired for the case of one-shot timers.  Once a periodic
timer is started, isRunning will return TRUE until it is cancelled.</dd>
<dt>isOneShot()</dt>
<dd>return TRUE if the timer is a one-shot timer.  Return FALSE
otherwise if the timer is a periodic timer.</dd>
<dt>startPeriodicAt(t0,dt)</dt>
<dd><p class="first">cancel any previously running timer and set to fire at time t1 =
t0+dt.  The timer will fire periodically every dt time units until
stopped.</p>
<p class="last">As with alarms, the time <tt class="docutils literal"><span class="pre">t0</span></tt> is always assumed to be in the past. A
value of <tt class="docutils literal"><span class="pre">t0</span></tt> numerically greater than the current time (returned by
<tt class="docutils literal"><span class="pre">getNow()</span></tt>) represents a time from before the last wraparound.</p>
</dd>
<dt>startOneShotAt(t0,dt)</dt>
<dd><p class="first">cancel any previously running timer and set to fire at time t1 =
t0+dt.  The timer will fire once then stop.</p>
<p class="last"><tt class="docutils literal"><span class="pre">t0</span></tt> is as in <tt class="docutils literal"><span class="pre">startPeriodicAt</span></tt>.</p>
</dd>
<dt>getNow()</dt>
<dd>return the current time in the precision and width of the timer.</dd>
<dt>gett0()</dt>
<dd>return the time anchor for the previously started timer or the time
of the previous event for periodic timers.</dd>
<dt>getdt()</dt>
<dd>return the delay or period for the previously started timer.</dd>
</dl>
</div>
</div>
<div class="section">
<h1><a id="hal-guidelines" name="hal-guidelines">3. HAL guidelines</a></h1>
<p>Platforms SHOULD expose their relevant timing capabilities using
standard Alarm and Counter interfaces.  The design pattern presented
here defines a component naming convention to allow platform
independent access to particular Alarms and Counters if they exist
and to cause compile errors if they do not.</p>
<p>A platform specific hardware timer with precision ${P} and width
${W} SHOULD be exposed as these two conventional Counter and Alarm
components:</p>
<pre class="literal-block">
configuration Counter${P}${W}C
{
  provides interface Counter&lt; T${P}, uint${W}_t &gt;;
}

generic configuration Alarm${P}${W}C()
{
  provides interface Alarm&lt; T${P}, uint${W}_t &gt;;
}
</pre>
<p>Instantiating an Alarm${P}${W}C component provides a new and independent
Alarm.  If the platform presents a limited number of Alarm resources,
then allocating more Alarms in an application than are available for the
platform SHOULD produce a compile-time error.  See Appendices B and C
for an example of how to make allocatable Alarms that are each
implemented on independent hardware timers.</p>
<p>For example, if a platform has an 8-bit 32kHz counter and three
8-bit 32kHz alarms, then the Counter and Alarm interfaces for
${P}=32khz and ${W}=16 are:</p>
<pre class="literal-block">
configuration Counter32khz8C
{
  provides interface Counter&lt; T32khz, uint8_t &gt;;
}

generic configuration Alarm32khz8C()
{
  provides interface Alarm&lt; T32khz, uint8_t &gt;;
}
</pre>
<p>This pattern MAY be used to define components for the platform that
are mutually incompatible in a single application.  Incompatible
components SHOULD produce compile-time errors when compiled
together.</p>
</div>
<div class="section">
<h1><a id="hil-requirements" name="hil-requirements">4. HIL requirements</a></h1>
<p>The following component MUST be provided on all platforms</p>
<pre class="literal-block">
HilTimerMilliC
BusyWaitMicroC
</pre>
<p>Both of these components use &quot;binary&quot; units, i.e., 1/1024s for
HilTimerMilliC and 1/1048576s for BusyWaitMicroC. Components using
other precisions (e.g., regular, non-binary milliseconds) MAY also be
provided.</p>
<div class="section">
<h2><a id="hiltimermillic" name="hiltimermillic">HilTimerMilliC</a></h2>
<pre class="literal-block">
configuration HilTimerMilliC
{
  provides interface Init;
  provides interface Timer&lt;TMilli&gt; as TimerMilli[ uint8_t num ];
  provides interface LocalTime&lt;TMilli&gt;;
}
</pre>
<p>A new timer is allocated using unique(UQ_TIMER_MILLI) to obtain a
new unique timer number.  This timer number is used to index the
TimerMilli parameterised interface.  UQ_TIMER_MILLI is defined in
Timer.h.  HilTimerMilliC is used by the LocalTimeMilliC component and the
TimerMilliC generic component, both found in <tt class="docutils literal"><span class="pre">tos/system/</span></tt></p>
</div>
<div class="section">
<h2><a id="busywaitmicroc" name="busywaitmicroc">BusyWaitMicroC</a></h2>
<pre class="literal-block">
configuration BusyWaitMicroC
{
  provides interface BusyWait&lt;TMicro,uint16_t&gt;;
}
</pre>
<p>BusyWaitMicroC allows applications to busy-wait for a number of
microseconds. Its use should be restricted to situations where the
delay is small and setting a timer or alarm would be impractical,
inefficient or insufficiently precise.</p>
</div>
</div>
<div class="section">
<h1><a id="utility-components" name="utility-components">5. Utility components</a></h1>
<p>A number of platform independent generic components are provided to
help implementers and advanced users of the TinyOS timer system:</p>
<ul class="simple">
<li>AlarmToTimerC</li>
<li>BusyWaitCounterC</li>
<li>CounterToLocalTimeC</li>
<li>TransformAlarmC</li>
<li>TransformCounterC</li>
<li>VirtualizeTimerC</li>
</ul>
<p>Appendices B and C show how these can be used to help implement
the timer HAL and HIL.</p>
<div class="section">
<h2><a id="alarmtotimerc" name="alarmtotimerc">AlarmToTimerC</a></h2>
<p>AlarmToTimerC converts a 32-bit Alarm to a Timer.</p>
<pre class="literal-block">
generic component AlarmToTimerC( typedef precision_tag )
{
  provides interface Timer&lt;precision_tag&gt;;
  uses interface Alarm&lt;precision_tag,uint32_t&gt;;
}
</pre>
</div>
<div class="section">
<h2><a id="busywaitcounterc" name="busywaitcounterc">BusyWaitCounterC</a></h2>
<p>BusyWaitCounterC uses a Counter to block until a specified amount of
time elapses.</p>
<pre class="literal-block">
generic component BusyWaitC( typedef precision_tag,
  typedef size_type &#64;integer() )
{
  provides interface BusyWait&lt;precision_tag,size_type&gt;;
  uses interface Counter&lt;precision_tag,size_type&gt;;
}
</pre>
</div>
<div class="section">
<h2><a id="countertolocaltimec" name="countertolocaltimec">CounterToLocalTimeC</a></h2>
<p>CounterToLocalTimeC converts from a 32-bit Counter to LocalTime.</p>
<pre class="literal-block">
generic component CounterToLocalTimeC( precision_tag )
{
  provides interface LocalTime&lt;precision_tag&gt;;
  uses interface Counter&lt;precision_tag,uint32_t&gt;;
}
</pre>
</div>
<div class="section">
<h2><a id="transformalarmc" name="transformalarmc">TransformAlarmC</a></h2>
<p>TransformAlarmC decreases precision and/or widens an Alarm.  An
already widened Counter component is used to help.</p>
<pre class="literal-block">
generic component TransformAlarmC(
  typedef to_precision_tag,
  typedef to_size_type &#64;integer(),
  typedef from_precision_tag,
  typedef from_size_type &#64;integer(),
  uint8_t bit_shift_right )
{
  provides interface Alarm&lt;to_precision_tag,to_size_type&gt; as Alarm;
  uses interface Counter&lt;to_precision_tag,to_size_type&gt; as Counter;
  uses interface Alarm&lt;from_precision_tag,from_size_type&gt; as AlarmFrom;
}
</pre>
<p>to_precision_tag and to_size_type describe the final precision and
final width for the provided Alarm.  from_precision_tag and
from_size_type describe the precision and width for the source
AlarmFrom.  bit_shift_right describes the bit-shift necessary to
convert from the used precision to the provided precision.</p>
<p>For instance to convert from an Alarm&lt;T32khz,uint16_t&gt; to an
Alarm&lt;TMilli,uint32_t&gt;, the following TransformAlarmC would be
created:</p>
<pre class="literal-block">
new TransformAlarmC( TMilli, uint32_t, T32khz, uint16_t, 5 )
</pre>
<p>It is the exclusive responsibility of the developer using
TransformAlarmC to ensure that all five of its arguments are self
consistent.  No compile errors are generated if the parameters
passed to TransformAlarmC are inconsistent.</p>
</div>
<div class="section">
<h2><a id="transformcounterc" name="transformcounterc">TransformCounterC</a></h2>
<p>TransformCounterC decreases precision and/or widens a Counter.</p>
<pre class="literal-block">
generic component TransformCounterC(
  typedef to_precision_tag,
  typedef to_size_type &#64;integer(),
  typedef from_precision_tag,
  typedef from_size_type &#64;integer(),
  uint8_t bit_shift_right,
  typedef upper_count_type &#64;integer() )
{
  provides interface Counter&lt;to_precision_tag,to_size_type&gt; as Counter;
  uses interface Counter&lt;from_precision_tag,from_size_type&gt; as CounterFrom;
}
</pre>
<p>to_precision_tag and to_size_type describe the final precision and
final width for the provided Counter.  from_precision_tag and
from_size_type describe the precision and width for the source
CounterFrom.  bit_shift_right describes the bit-shift necessary to
convert from the used precision to the provided precision.
upper_count_type describes the numeric type used to store the
additional counter bits.  upper_count_type MUST be a type with width
greater than or equal to the additional bits in to_size_type plus
bit_shift_right.</p>
<p>For instance to convert from a Counter&lt;T32khz,uint16_t&gt; to a
Counter&lt;TMilli,uint32_t&gt;, the following TransformCounterC would be
created:</p>
<pre class="literal-block">
new TransformCounterC( TMilli, uint32_t, T32khz, uint16_t, 5, uint32_t )
</pre>
</div>
<div class="section">
<h2><a id="virtualizetimerc" name="virtualizetimerc">VirtualizeTimerC</a></h2>
<p>VirtualizeTimerC uses a single Timer to create up to 255 virtual
timers.</p>
<pre class="literal-block">
generic component VirtualizeTimerC( typedef precision_tag, int max_timers )
{
  provides interface Init;
  provides interface Timer&lt;precision_tag&gt; as Timer[ uint8_t num ];
  uses interface Timer&lt;precision_tag&gt; as TimerFrom;
}
</pre>
</div>
</div>
<div class="section">
<h1><a id="implementation" name="implementation">6. Implementation</a></h1>
<p>The definition of the HIL interfaces are found in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/timer</span></tt>:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">Alarm.nc</span></tt></li>
<li><tt class="docutils literal"><span class="pre">BusyWait.nc</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Counter.nc</span></tt></li>
<li><tt class="docutils literal"><span class="pre">LocalTime.nc</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Timer.h</span></tt> defines precision tags and strings for unique()</li>
<li><tt class="docutils literal"><span class="pre">Timer.nc</span></tt></li>
</ul>
</blockquote>
<p>The implementation of the utility components are also found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/timer</span></tt>:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">AlarmToTimerC.nc</span></tt></li>
<li><tt class="docutils literal"><span class="pre">BusyWaitCounterC.nc</span></tt></li>
<li><tt class="docutils literal"><span class="pre">CounterToLocalTimeC.nc</span></tt></li>
<li><tt class="docutils literal"><span class="pre">TransformAlarmC.nc</span></tt></li>
<li><tt class="docutils literal"><span class="pre">TransformCounterC.nc</span></tt></li>
<li><tt class="docutils literal"><span class="pre">VirtualizeAlarmC.nc</span></tt></li>
<li><tt class="docutils literal"><span class="pre">VirtualizeTimerC.nc</span></tt></li>
</ul>
</blockquote>
<p>The implementation of timers for the MSP430 is in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/msp430/timer</span></tt>:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">Alarm32khz16C.nc</span></tt> is generic and provides a new <tt class="docutils literal"><span class="pre">Alarm&lt;T32khz,uint16_t&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Alarm32khz32C.nc</span></tt> is generic and provides a new <tt class="docutils literal"><span class="pre">Alarm&lt;T32khz,uint32_t&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">AlarmMilli16C.nc</span></tt> is generic and provides a new <tt class="docutils literal"><span class="pre">Alarm&lt;TMilli,uint16_t&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">AlarmMilli32C.nc</span></tt> is generic and provides a new <tt class="docutils literal"><span class="pre">Alarm&lt;TMilli,uint32_t&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">BusyWait32khzC.nc</span></tt> provides <tt class="docutils literal"><span class="pre">BusyWait&lt;T32khz,uint16_t&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">BusyWaitMicroC.nc</span></tt> provides <tt class="docutils literal"><span class="pre">BusyWait&lt;TMicro,uint16_t&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Counter32khz16C.nc</span></tt> provides <tt class="docutils literal"><span class="pre">Counter&lt;T32khz,uint16_t&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Counter32khz32C.nc</span></tt> provides <tt class="docutils literal"><span class="pre">Counter&lt;T32khz,uint32_t&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">CounterMilli16C.nc</span></tt> provides <tt class="docutils literal"><span class="pre">Counter&lt;TMilli,uint16_t&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">CounterMilli32C.nc</span></tt> provides <tt class="docutils literal"><span class="pre">Counter&lt;TMilli,uint32_t&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">GpioCaptureC.nc</span></tt></li>
<li><tt class="docutils literal"><span class="pre">HilTimerMilliC.nc</span></tt> provides <tt class="docutils literal"><span class="pre">LocalTime&lt;TMilli&gt;</span></tt> and
<tt class="docutils literal"><span class="pre">Timer&lt;TMilli&gt;</span> <span class="pre">as</span> <span class="pre">TimerMilli[uint8_t</span> <span class="pre">num]</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Msp430AlarmC.nc</span></tt> is generic and converts an MSP430 timer to a 16-bit Alarm</li>
<li><tt class="docutils literal"><span class="pre">Msp430Capture.nc</span></tt> HPL interface definition for MSP430 timer captures</li>
<li><tt class="docutils literal"><span class="pre">Msp430ClockC.nc</span></tt> exposes MSP430 hardware clock initialization</li>
<li><tt class="docutils literal"><span class="pre">Msp430ClockInit.nc</span></tt> HPL interface definition for hardware clock initialization</li>
<li><tt class="docutils literal"><span class="pre">Msp430ClockP.nc</span></tt> implements MSP430 hardware clock initialization and
calibration and startup</li>
<li><tt class="docutils literal"><span class="pre">Msp430Compare.nc</span></tt> HPL interface definition for MSP430 timer compares</li>
<li><tt class="docutils literal"><span class="pre">Msp430Counter32khzC.nc</span></tt> provides <tt class="docutils literal"><span class="pre">Counter&lt;T32khz,uint16_t&gt;</span></tt> based on
MSP430 TimerB</li>
<li><tt class="docutils literal"><span class="pre">Msp430CounterC.nc</span></tt> is generic and converts an Msp430Timer to a Counter</li>
<li><tt class="docutils literal"><span class="pre">Msp430CounterMicroC.nc</span></tt> provides <tt class="docutils literal"><span class="pre">Counter&lt;TMicro,uint16_t&gt;</span></tt> based on
MSP430 TimerA</li>
<li><tt class="docutils literal"><span class="pre">Msp430Timer.h</span></tt> defines additional MSP430 timer bitmasks and structs</li>
<li><tt class="docutils literal"><span class="pre">Msp430Timer.nc</span></tt> HPL interface definition</li>
<li><tt class="docutils literal"><span class="pre">Msp430Timer32khzC.nc</span></tt> is generic and allocates a new 32khz hardware timer</li>
<li><tt class="docutils literal"><span class="pre">Msp430Timer32khzMapC.nc</span></tt> exposes the MSP430 hardware timers as a
parameterized interface allocatable using Msp430Timer32khzC</li>
<li><tt class="docutils literal"><span class="pre">Msp430TimerC.nc</span></tt> exposes the MSP430 hardware timers</li>
<li><tt class="docutils literal"><span class="pre">Msp430TimerCapComP.nc</span></tt> is generic and implements the HPL for MSP430
capture/compare special function registers</li>
<li><tt class="docutils literal"><span class="pre">Msp430TimerCommonP.nc</span></tt> maps the MSP430 timer interrupts to Msp430TimerEvents</li>
<li><tt class="docutils literal"><span class="pre">Msp430TimerControl.nc</span></tt> HPL interface definition</li>
<li><tt class="docutils literal"><span class="pre">Msp430TimerEvent.nc</span></tt> HPL interface definition</li>
<li><tt class="docutils literal"><span class="pre">Msp430TimerP.nc</span></tt> is generic and implements the HPL for MSP430 timer
special function registers</li>
</ul>
</blockquote>
<p>Implementation of timers for the ATmega128 and PXA27x may be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/atm128/timer</span></tt> and
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/pxa27x/timer</span></tt> respectively.</p>
</div>
<div class="section">
<h1><a id="author-s-address" name="author-s-address">7. Author's Address</a></h1>
<div class="line-block">
<div class="line">Cory Sharp</div>
<div class="line">Moteiv Corporation</div>
<div class="line">55 Hawthorne St, Suite 550</div>
<div class="line">San Francisco, CA 94105</div>
<div class="line"><br /></div>
<div class="line">phone - +1 415 692 0963</div>
<div class="line">email - <a class="reference" href="mailto:cory&#64;moteiv.com">cory&#64;moteiv.com</a></div>
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line">Martin Turon</div>
<div class="line">P.O. Box 8525</div>
<div class="line">Berkeley, CA 94707</div>
<div class="line"><br /></div>
<div class="line">phone - +1 408 965 3355</div>
<div class="line">email - <a class="reference" href="mailto:mturon&#64;xbow.com">mturon&#64;xbow.com</a></div>
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line">David Gay</div>
<div class="line">2150 Shattuck Ave, Suite 1300</div>
<div class="line">Intel Research</div>
<div class="line">Berkeley, CA 94704</div>
<div class="line"><br /></div>
<div class="line">phone - +1 510 495 3055</div>
<div class="line">email - <a class="reference" href="mailto:david.e.gay&#64;intel.com">david.e.gay&#64;intel.com</a></div>
</div>
</div>
<div class="section">
<h1><a id="appendix-a-timer-hardware-on-various-microcontrollers" name="appendix-a-timer-hardware-on-various-microcontrollers">Appendix A: Timer hardware on various microcontrollers</a></h1>
<blockquote>
<ol class="loweralpha simple">
<li>Atmega128</li>
</ol>
<blockquote>
<ol class="lowerroman simple">
<li>Two 8-bit timers, each allowing</li>
</ol>
<blockquote>
<ul class="simple">
<li>7 prescaler values (division by different powers of 2)</li>
<li>Timer 0 can use an external 32768Hz crystal</li>
<li>One compare register, with many compare actions (change
output pin, clear counter, generate interrupt, etc)</li>
</ul>
</blockquote>
<ol class="lowerroman simple" start="2">
<li>Two 16-bit timers, each with</li>
</ol>
<blockquote>
<ul class="simple">
<li>5 prescaler values</li>
<li>External and software clocking options</li>
<li>Three compare registers (again with many actions)</li>
<li>Input capture</li>
</ul>
</blockquote>
</blockquote>
<ol class="loweralpha simple" start="2">
<li>MSP430</li>
</ol>
<blockquote>
<ol class="lowerroman simple">
<li>Two 16-bit timers with</li>
</ol>
<blockquote>
<ul class="simple">
<li>One with three compare registers</li>
<li>One with eight compare registers</li>
<li>Each from distinct clock source</li>
<li>Each with limited prescalers</li>
</ul>
</blockquote>
</blockquote>
<ol class="loweralpha simple" start="3">
<li>Intel PXA27x</li>
</ol>
<blockquote>
<ol class="lowerroman simple">
<li>One fixed rate (3.25MHz) 32-bit timer with</li>
</ol>
<blockquote>
<ul class="simple">
<li>4 compare registers</li>
<li>Watchdog functionality</li>
</ul>
</blockquote>
<ol class="lowerroman simple" start="2">
<li>8 variable rate 32-bit timers with</li>
</ol>
<blockquote>
<ul class="simple">
<li>1 associated compare register each</li>
<li>Individually selectable rates: 1/32768s, 1ms, 1s, 1us</li>
<li>Individually selectable sources: (32.768 external osc,
13 Mhz internal clock)</li>
</ul>
</blockquote>
<ol class="lowerroman simple" start="3">
<li>Periodic &amp; one-shot capability</li>
<li>Two external sync events</li>
</ol>
</blockquote>
</blockquote>
</div>
<div class="section">
<h1><a id="appendix-b-a-microcontroller-atmega-128-timer-subsystem" name="appendix-b-a-microcontroller-atmega-128-timer-subsystem">Appendix B: a microcontroller: Atmega 128 timer subsystem</a></h1>
<p>The Atmega128 exposes its four timers through a common set of interfaces:</p>
<blockquote>
<ul class="simple">
<li>HplTimer&lt;width&gt;   - get/set current time, overflow event, control, init</li>
<li>HplCompare&lt;width&gt; - get/set compare time, fired event,    control</li>
<li>HplCapture&lt;width&gt; - get/set capture time, captured event, control, config</li>
</ul>
</blockquote>
<p>Parameterising these interfaces by width allows reusing the same interfaces
for the 8 and 16-bit timers. This simplifies building reusable higher level
components which are independent of timer width.</p>
<pre class="literal-block">
interface HplAtm128Timer&lt;timer_size&gt;
{
  /// Timer value register: Direct access
  async command timer_size get();
  async command void       set( timer_size t );

  /// Interrupt signals
  async event void overflow();        //&lt;! Signalled on overflow interrupt

  /// Interrupt flag utilites: Bit level set/clr
  async command void reset(); //&lt;! Clear the overflow interrupt flag
  async command void start(); //&lt;! Enable the overflow interrupt
  async command void stop();  //&lt;! Turn off overflow interrupts
  async command bool test();  //&lt;! Did overflow interrupt occur?
  async command bool isOn();  //&lt;! Is overflow interrupt on?

  /// Clock initialization interface
  async command void    off();                     //&lt;! Turn off the clock
  async command void    setScale( uint8_t scale);  //&lt;! Turn on the clock
  async command uint8_t getScale();                //&lt;! Get prescaler setting
}

interface HplAtm128Compare&lt;size_type&gt;
{
  /// Compare value register: Direct access
  async command size_type get();
  async command void      set(size_type t);

  /// Interrupt signals
  async event void fired();           //&lt;! Signalled on compare interrupt

  /// Interrupt flag utilites: Bit level set/clr
  async command void reset();         //&lt;! Clear the compare interrupt flag
  async command void start();         //&lt;! Enable the compare interrupt
  async command void stop();          //&lt;! Turn off comparee interrupts
  async command bool test();          //&lt;! Did compare interrupt occur?
  async command bool isOn();          //&lt;! Is compare interrupt on?
}

interface HplAtm128Capture&lt;size_type&gt;
{
  /// Capture value register: Direct access
  async command size_type get();
  async command void      set(size_type t);

  /// Interrupt signals
  async event void captured(size_type t);  //&lt;! Signalled on capture int

  /// Interrupt flag utilites: Bit level set/clr
  async command void reset();          //&lt;! Clear the capture interrupt flag
  async command void start();          //&lt;! Enable the capture interrupt
  async command void stop();           //&lt;! Turn off capture interrupts
  async command bool test();           //&lt;! Did capture interrupt occur?
  async command bool isOn();           //&lt;! Is capture interrupt on?

  async command void setEdge(bool up); //&lt;! True = detect rising edge
}
</pre>
<p>These interfaces are provided by four components, corresponding to each
hardware timer: HplAtm128Timer0AsyncC, and HplAtm128Timer0C through
HplAtm128Timer3C. Timers 1 and 3 have three compare registers, so offer
a parameterised HplAtm128Compare interface:</p>
<pre class="literal-block">
configuration HplAtm128Timer1C
{
  provides {
    // 16-bit Timers
    interface HplAtm128Timer&lt;uint16_t&gt;   as Timer;
    interface HplAtm128TimerCtrl16       as TimerCtrl;
    interface HplAtm128Capture&lt;uint16_t&gt; as Capture;
    interface HplAtm128Compare&lt;uint16_t&gt; as Compare[uint8_t id];
  }
}
...
</pre>
<p>where the <tt class="docutils literal"><span class="pre">id</span></tt> corresponds to the compare register number. The parameterised
interface is only connected for <tt class="docutils literal"><span class="pre">id</span></tt> equal to 0, 1 or 2. Attempts to use
another value cause a compile-time error. This is achieved as follows (code
from the implementation of <tt class="docutils literal"><span class="pre">HplAtm128Timer1C</span></tt>)</p>
<pre class="literal-block">
Compare[0] = HplAtm128Timer1P.CompareA;
Compare[1] = HplAtm128Timer1P.CompareB;
Compare[2] = HplAtm128Timer1P.CompareC;
</pre>
<p>The Atmega128 chip components do not define a HAL, as the timer
configuration choices (frequencies, use of input capture or compare output,
etc) are platform-specific. Instead, it provides a few generic components
for converting the HPL interfaces into platform-independent interfaces.
These generic components include appropriate configuration parameters
(e.g., prescaler values):</p>
<pre class="literal-block">
generic module Atm128AlarmC(typedef frequency_tag,
                            typedef timer_size &#64;integer(),
                            uint8_t prescaler,
                            int mindt)
{
  provides interface Init;
  provides interface Alarm&lt;frequency_tag, timer_size&gt; as Alarm;
  uses interface HplTimer&lt;timer_size&gt;;
  uses interface HplCompare&lt;timer_size&gt;;
} ...

generic module Atm128CounterC(typedef frequency_tag,
                              typedef timer_size &#64;integer())
{
  provides interface Counter&lt;frequency_tag,timer_size&gt; as Counter;
  uses interface HplTimer&lt;timer_size&gt; as Timer;
} ...
</pre>
<p>As a result of issues arising from using timer 0 in asynchronous mode,
the HAL also offers the following component:</p>
<pre class="literal-block">
generic configuration Atm128AlarmAsyncC(typedef precision, int divider) {
  provides {
    interface Init &#64;atleastonce();
    interface Alarm&lt;precision, uint32_t&gt;;
    interface Counter&lt;precision, uint32_t&gt;;
  }
}
...
</pre>
<p>which builds a 32-bit alarm and timer over timer 0. divider is used
to initialise the timer0 scaling factor.</p>
</div>
<div class="section">
<h1><a id="appendix-c-a-mote-mica-family-timer-subsystem" name="appendix-c-a-mote-mica-family-timer-subsystem">Appendix C: a mote: Mica family timer subsystem</a></h1>
<p>Members of the mica family (mica2, mica2dot, micaz) use the Atmega128
microprocessor and have external crystals at 4 or 7.37MHz. Additionally,
they can be run from an internal oscillator at 1, 2, 4, or 8 MHz. The
internal oscillator is less precise, but allows for much faster startup
from power-down and power-save modes (6 clocks vs 16000 clocks). Finally,
power consumption is lower at the lower frequencies.</p>
<p>The mica family members support operation at all these frequencies via
a <tt class="docutils literal"><span class="pre">MHZ</span></tt> preprocessor symbol, which can be defined to 1, 2, 4, or 8.
If undefined, it defaults to a platform-dependent value (4 for mica2dot,
8 for mica2 and micaz).</p>
<p>The mica family configures its four timers in part based on the value
of this MHZ symbol:</p>
<ul>
<li><p class="first">Timer 0: uses Atm128AlarmAsyncC to divide the external 32768Hz crystal
by 32, creating a 32-bit alarm and counter. This alarm and counter is
used to build HilTimerMilliC, using the AlarmToTimerC,
VirtualizeTimerC and CounterToLocalTimeC utility components.</p>
<p>Timing accuracy is as good as the external crystal.</p>
</li>
<li><p class="first">Timer 1: the 16-bit hardware timer 1 is set to run at 1MHz if possible.
However, the set of dividers for timer 1 is limited to 1, 8,
64, 256 and 1024. So, when clocked at 2 or 4MHz, a divider of 1 is
selected and timer 1 runs at 2 or 4MHz. To reflect this fact, the
HAL components exposing timer 1 are named <tt class="docutils literal"><span class="pre">CounterOne16C</span></tt> and
<tt class="docutils literal"><span class="pre">AlarmOne16C</span></tt> (rather than the <tt class="docutils literal"><span class="pre">CounterMicro16C</span></tt> <tt class="docutils literal"><span class="pre">AlarmMicro16C</span></tt>
as suggested in Section 3).</p>
<p>32-bit microsecond Counters and Alarms, named <tt class="docutils literal"><span class="pre">CounterMicro32C</span></tt> and
<tt class="docutils literal"><span class="pre">AlarmMicro32C</span></tt>, are created from <tt class="docutils literal"><span class="pre">CounterOne16C</span></tt> and
<tt class="docutils literal"><span class="pre">AlarmOne16C</span></tt> using the TransformAlarmC and TransformCounterC
utility components.</p>
<p>Three compare registers are available on timer1, so up to three instances
of <tt class="docutils literal"><span class="pre">AlarmOne16C</span></tt> and/or <tt class="docutils literal"><span class="pre">AlarmMicro32C</span></tt> can be created. The timing
accuracy depends on how the mote is clocked:</p>
<ul class="simple">
<li>internal clock: depends on how well the clock is calibrated</li>
<li>external 7.37MHz crystal: times will be off by ~8.6%</li>
<li>external 4MHz crystal: times will be as accurate as the crystal</li>
</ul>
</li>
<li><p class="first">Timer 2: this timer is not currently exposed by the HAL.</p>
</li>
<li><p class="first">Timer 3: the 16-bit hardware timer 3 is set to run at a rate close to
32768Hz, if possible. As with timer 1, the limited set of dividers makes
this impossible at some clock frequencies, so the 16-bit timer 3 HAL
components are named <tt class="docutils literal"><span class="pre">CounterThree16C</span></tt> and <tt class="docutils literal"><span class="pre">AlarmThree16C</span></tt>. As
with timer 1, the rate of timer 3 is adjusted in software to
build 32-bit counter and 32-bit alarms, giving components
<tt class="docutils literal"><span class="pre">Counter32khz32C</span></tt> and <tt class="docutils literal"><span class="pre">Alarm32khz32C</span></tt>. As with timer 1, three compare
registers, hence up to three instances of <tt class="docutils literal"><span class="pre">Alarm32khz32C</span></tt> and/or
<tt class="docutils literal"><span class="pre">AlarmThree16C</span></tt> are available.</p>
<p>At 1, 2, 4 and 8MHz, <tt class="docutils literal"><span class="pre">Counter32khz32C</span></tt> and <tt class="docutils literal"><span class="pre">Alarm32khz32C</span></tt> run
at 31.25kHz (plus clock rate inaccuracy). At 7.37MHz, they run at
~28.8kHz.</p>
</li>
</ul>
<p>The automatic allocation of compare registers to alarms (and
corresponding compile-time error when too many compare registers are
used) is achieved as follows.  The implementations of <tt class="docutils literal"><span class="pre">AlarmOne16C</span></tt>
and <tt class="docutils literal"><span class="pre">AlarmThree16C</span></tt> use the <tt class="docutils literal"><span class="pre">Atm128AlarmC</span></tt> generic component and
wire it, using <tt class="docutils literal"><span class="pre">unique</span></tt>, to one of the compare registers offered by
<tt class="docutils literal"><span class="pre">HplAtm128Timer1C</span></tt> and <tt class="docutils literal"><span class="pre">HplAtm128Timer3C</span></tt>:</p>
<pre class="literal-block">
generic configuration AlarmOne16C()
{
  provides interface Alarm&lt;TOne, uint16_t&gt;;
}
implementation
{
  components HplAtm128Timer1C, InitOneP,
    new Atm128AlarmC(TOne, uint16_t, 3) as NAlarm;

  Alarm = NAlarm;
  NAlarm.HplAtm128Timer -&gt; HplAtm128Timer1C.Timer;
  NAlarm.HplAtm128Compare -&gt; HplAtm128Timer1C.Compare[unique(UQ_TIMER1_COMPARE)];
}
</pre>
<p>On the fourth creation of an <tt class="docutils literal"><span class="pre">AlarmOne16C</span></tt>, <tt class="docutils literal"><span class="pre">unique(UQ_TIMER1_COMPARE)</span></tt>
will return 3, causing a compile-time error as discussed in Appendix B
(<tt class="docutils literal"><span class="pre">HplAtm128Timer1C</span></tt>'s <tt class="docutils literal"><span class="pre">Compare</span></tt> interface is only defined for values
from 0 to 2).</p>
<p>When an Atmega128 is in any power-saving mode, hardware timers 1, 2 and 3
stop counting. The default Atmega128 power management <em>will</em> enter these
power-saving modes even when timers 1 and 3 are enabled, so time as
measured by timers 1 and 3 does <em>not</em> represent real time.  However, if any
alarms built on timers 1 or 3 are active, the Atmega128 power management
will not enter power-saving modes.</p>
<p>The mica family HIL components are built as follows:</p>
<ul class="simple">
<li>HilTimerMilliC: built as described above from hardware timer 0.</li>
<li>BusyWaitMicroC: implemented using a simple software busy-wait loop which
waits for <tt class="docutils literal"><span class="pre">MHZ</span></tt> cycles per requested microsecond. Accuracy is the same as
Timer 1.</li>
</ul>
<p>Finally, the mica family motes measure their clock rate at boot time, based
on the external 32768Hz crystal. The results of this clock rate measurement
are made available via the <tt class="docutils literal"><span class="pre">cyclesPerJiffy</span></tt> command of the
<tt class="docutils literal"><span class="pre">Atm128Calibrate</span></tt> interface of the <tt class="docutils literal"><span class="pre">MeasureClockC</span></tt> component. This
command reports the number of cycles per 1/32768s. Please see this interface
definition for other useful commands for more accurate timing.</p>
</div>
</div>
</body>
</html>
